

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>贡献 Ceph 文档 &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />

  
  
    <link rel="shortcut icon" href="../../_static/favicon.ico"/>
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/underscore.js"></script>
        <script src="../../_static/doctools.js"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="安装 Ceph" href="../../install/" />
    <link rel="prev" title="加入 Ceph 社区！" href="../get-involved/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    

















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../../" class="icon icon-home"></a> &raquo;</li>
        
          <li><a href="../intro/">Ceph 简介</a> &raquo;</li>
        
      <li>贡献 Ceph 文档</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../../_sources/start/documenting-ceph.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../">
          

          
            
            <img src="../../_static/logo.png" class="logo" alt="Logo"/>
          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../intro/">Ceph 简介</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../hardware-recommendations/">硬件推荐</a></li>
<li class="toctree-l2"><a class="reference internal" href="../os-recommendations/">操作系统推荐</a></li>
<li class="toctree-l2"><a class="reference internal" href="../get-involved/">加入 Ceph 社区！</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">贡献 Ceph 文档</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id1">文档在源码库里的位置</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id2">怎么看以前的 Ceph 文档</a></li>
<li class="toctree-l3"><a class="reference internal" href="#making-contributions">如何贡献</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id4">获取源代码</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id5">进入分支</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id6">开始更改</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id7">构建文档源码</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id9">提交变更</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id10">推送变更</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id11">发出接收请求</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id12">通知我们</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#id13">文档风格指南</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id14">标题</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id15">正文</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id16">段落分级标记</a></li>
<li class="toctree-l4"><a class="reference internal" href="#toc">TOC 和超链接</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../radosgw/">Ceph 对象网关</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <div class="section" id="ceph">
<h1>贡献 Ceph 文档<a class="headerlink" href="#ceph" title="Permalink to this headline">¶</a></h1>
<p>想帮助 Ceph 项目可以贡献文档。
即使是小小的贡献也对 Ceph 项目有益，
比如修正拼写错误或者重写含糊不清的语句。</p>
<p>纠正文档最简单的方法就是往 <cite>ceph-users&#64;ceph.io</cite> 发送电子邮件。在标题行写上
“ATTN: DOCS” 或者 “Attention: Docs” 或者 “Attention: Documentation” 。
在 email 正文，写上要纠正的文本（以便我在代码库里找到它）、还有你的更正。</p>
<p>纠正文档的另外一种方法是发出一个拉取请求。
向 Ceph 文档提出拉取请求的说明位于 <a class="reference internal" href="#making-contributions"><span class="std std-ref">如何贡献</span></a> 。</p>
<p>如果这是你第一次改进文档、或者假设你发现了一个小小的错误（比如拼写错误或者错别字），
发一封邮件比提出拉取请求更简单。
这次改进将归功于你，除非你向 Ceph 文档上游明确提出不要归功于你。</p>
<div class="section" id="id1">
<h2>文档在源码库里的位置<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>Ceph 文档源码位于 Ceph 源码库的 <code class="docutils literal notranslate"><span class="pre">ceph/doc</span></code> 目录下，由 Python Sphinx 渲染成 HTML 和手册页。</p>
</div>
<div class="section" id="id2">
<h2>怎么看以前的 Ceph 文档<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="https://docs.ceph.com">https://docs.ceph.com</a> 链接默认展示 <code class="docutils literal notranslate"><span class="pre">master</span></code> 分支，也可以查看较早版本
（如 <code class="docutils literal notranslate"><span class="pre">mimic</span></code> ）的文档，把 URL 里（如
<a class="reference external" href="https://docs.ceph.com/en/pacific">https://docs.ceph.com/en/pacific</a> 里的 <code class="docutils literal notranslate"><span class="pre">pacific</span></code> ）
的版本名替换成你想看的分支即可（如 <code class="docutils literal notranslate"><span class="pre">mimic</span></code> ， URL 就成了
<a class="reference external" href="https://docs.ceph.com/en/mimic/">https://docs.ceph.com/en/mimic/</a> ）。</p>
</div>
<div class="section" id="making-contributions">
<span id="id3"></span><h2>如何贡献<a class="headerlink" href="#making-contributions" title="Permalink to this headline">¶</a></h2>
<p>贡献文档和贡献源码的过程基本相同，唯一不同的就是你编译的是文档源码而不是程序源码。大致顺序（编译文档源码的顺序）如下：</p>
<ol class="arabic simple">
<li><p><a class="reference internal" href="#id4">获取源代码</a></p></li>
<li><p><a class="reference internal" href="#id5">进入分支</a></p></li>
<li><p><a class="reference internal" href="#id6">开始更改</a></p></li>
<li><p><a class="reference internal" href="#id7">构建文档源码</a></p></li>
<li><p><a class="reference internal" href="#id9">提交变更</a></p></li>
<li><p><a class="reference internal" href="#id10">推送变更</a></p></li>
<li><p><a class="reference internal" href="#id11">发出接收请求</a></p></li>
<li><p><a class="reference internal" href="#id12">通知我们</a></p></li>
</ol>
<div class="section" id="id4">
<h3>获取源代码<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
<p>Ceph 文档位于和源码同一仓库内的 <code class="docutils literal notranslate"><span class="pre">ceph/doc</span></code> 目录下，关于 github 和 Ceph 的关系细节情况见<a class="reference internal" href="../get-involved/#get-involved"><span class="std std-ref">加入 Ceph 社区！</span></a>。</p>
<p>最常用的贡献方法是<a class="reference external" href="https://help.github.com/articles/using-pull-requests">分支并拉取</a>。为此，必须先做到：</p>
<ol class="arabic">
<li><p>在本地安装 git 。在 Debian/Ubuntu 下用此命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><style type="text/css">
span.prompt1:before {
  content: "$ ";
}
</style><span class="prompt1">sudo apt-get install git</span>
</pre></div></div><p>在 Fedora 下用此命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo yum install git</span>
</pre></div></div><p>在 CentOS/RHEL 下用此命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo yum install git</span>
</pre></div></div></li>
<li><p>在 <code class="docutils literal notranslate"><span class="pre">.gitconfig</span></code> 配置文件里写好自己的名字和邮件地址。</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[user]</span>
   <span class="na">email</span> <span class="o">=</span> <span class="s">{your-email-address}</span>
   <span class="na">name</span> <span class="o">=</span> <span class="s">{your-name}</span>
</pre></div>
</div>
<p>例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git config --global user.name <span class="s2">&quot;John Doe&quot;</span></span>
<span class="prompt1">git config --global user.email johndoe@example.com</span>
</pre></div></div></li>
<li><p>创建 <a class="reference external" href="http://github.com">github</a> 帐户（假如没有的话）。</p></li>
<li><p>创建 Ceph 项目的分支，参见 <a class="reference external" href="https://github.com/ceph/ceph">https://github.com/ceph/ceph</a> 。</p></li>
<li><p>把已分支项目克隆到本机。</p></li>
</ol>
<p>Ceph 文档按它自身的主要组件来分类组织。</p>
<ul class="simple">
<li><p><strong>Ceph 存储集群：</strong>Ceph 存储集群文档位于
<code class="docutils literal notranslate"><span class="pre">doc/rados</span></code> 目录下；</p></li>
<li><p><strong>Ceph 块设备：</strong>Ceph 块设备文档位于
<code class="docutils literal notranslate"><span class="pre">doc/rbd</span></code> 目录下；</p></li>
<li><p><strong>Ceph 对象存储：</strong>Ceph 对象存储文档位于
<code class="docutils literal notranslate"><span class="pre">doc/radosgw</span></code> 目录下；</p></li>
<li><p><strong>Ceph 文件系统：</strong>Ceph 文件系统文档位于
<code class="docutils literal notranslate"><span class="pre">doc/cephfs</span></code> 目录下；</p></li>
<li><p><strong>安装（快速）：</strong>快速入门文档位于
<code class="docutils literal notranslate"><span class="pre">doc/start</span></code> 目录下；</p></li>
<li><p><strong>安装（手动）：</strong>手动安装文档位于
<code class="docutils literal notranslate"><span class="pre">doc/install</span></code> 目录下；</p></li>
<li><p><strong>手册页：</strong>手册源码位于 <code class="docutils literal notranslate"><span class="pre">doc/man</span></code> 目录下；</p></li>
<li><p><strong>开发者：</strong>开发者文档位于 <code class="docutils literal notranslate"><span class="pre">doc/dev</span></code> 目录下；</p></li>
<li><p><strong>图片：</strong>如果你想上传文档，如 JPEG 或 PNG 文件，
应该放到 <code class="docutils literal notranslate"><span class="pre">doc/images</span></code> 目录下。</p></li>
</ul>
</div>
<div class="section" id="id5">
<h3>进入分支<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
<p>如果只是细小的变更，像修正排版错误、或换一种措辞，
直接提交到 <code class="docutils literal notranslate"><span class="pre">master</span></code> 分支（默认的）即可；
为当前版本的功能提供文档时也应该提交到 <code class="docutils literal notranslate"><span class="pre">master</span></code> 分支。
<code class="docutils literal notranslate"><span class="pre">master</span></code> 是最常用的分支。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git checkout master</span>
</pre></div></div><p>给未来版本提供文档时应该提交到 <code class="docutils literal notranslate"><span class="pre">next</span></code> 分支，
<code class="docutils literal notranslate"><span class="pre">next</span></code> 分支是第二常用的分支。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git checkout next</span>
</pre></div></div><p>你在为尚未发布的功能写文档时，
如果这部分文档和已追踪的某个问题有关，
或者想在它被合并到 <code class="docutils literal notranslate"><span class="pre">master</span></code> 分支前看看它在 ceph.com 网站上的预览，
你应该另外创建个分支。为标识这是个只包含文档的更新，
按惯例用 <code class="docutils literal notranslate"><span class="pre">wip-doc</span></code> 作前缀，
按这个格式 <code class="docutils literal notranslate"><span class="pre">wip-doc-{your-branch-name}</span></code> 。
如果此分支和 <a class="reference external" href="http://tracker.ceph.com/issues">http://tracker.ceph.com/issues</a> 里的某个问题相关，
分支名最好包含问题编号，
例如，如果某文档分支是为 #4000 这个问题写的，
按惯例这个分支名就是 <code class="docutils literal notranslate"><span class="pre">wip-doc-4000</span></code> ，
对应的问题追踪 URL 就是 <a class="reference external" href="http://tracker.ceph.com/issues/4000">http://tracker.ceph.com/issues/4000</a> 。</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>请不要把贡献的文档和源码混合到同一个提交里，
您的文档提交和源码提交分开时，
会简化审查进程。
我们强烈建议所有新增功能或配置选项的拉取请求也要包含一个文档提交，
描述一下相关的变更、选项。</p>
</div>
<p>创建分支前，确保本地和远程都没有同名的。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git branch -a <span class="p">|</span> grep wip-doc-<span class="o">{</span>your-branch-name<span class="o">}</span></span>
</pre></div></div><p>如果确实不存在，就可以创建了：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git checkout -b wip-doc-<span class="o">{</span>your-branch-name<span class="o">}</span></span>
</pre></div></div></div>
<div class="section" id="id6">
<h3>开始更改<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
<p>修改文档很简单，打开 restructuredText 文件、修改、保存即可。
相关的语法请参考 <a class="reference internal" href="#id13">文档风格指南</a> 。</p>
<p>新增文档要在 <code class="docutils literal notranslate"><span class="pre">doc</span></code> 目录或其子目录下新建 restructuredText 文件，
并以 <code class="docutils literal notranslate"><span class="pre">*.rst</span></code> 作后缀。
还必须包含对它的引用：
如超链接或目录条目。某个顶极目录中的 <code class="docutils literal notranslate"><span class="pre">index.rst</span></code> 文件通常也包含一个 TOC ，
你可以在这里添加新文件名。
所有文档都必须有标题，详情见<a class="reference internal" href="#id14">标题</a>。</p>
<p>你新建的文档不会自动被 <code class="docutils literal notranslate"><span class="pre">git</span></code> 跟踪，
如果想把它加进仓库，必须用 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">{path-to-filename}</span></code> 命令。
比如，在 Ceph 仓库的顶极目录下，
把 <code class="docutils literal notranslate"><span class="pre">example.rst</span></code> 文件加到 <code class="docutils literal notranslate"><span class="pre">rados</span></code> 子目录下，
可以这样：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git add doc/rados/example.rst</span>
</pre></div></div><p>要删除一文档，应该用 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rm</span> <span class="pre">{path-to-filename}</span></code> ，
比如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git rm doc/rados/example.rst</span>
</pre></div></div><p>还必须从其他文档删除与之相关的引用。</p>
</div>
<div class="section" id="id7">
<h3>构建文档源码<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
<p>要想构建文档，先进入 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 库目录：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1"><span class="nb">cd</span> ceph</span>
</pre></div></div><div class="admonition note">
<p class="admonition-title">Note</p>
<p>包含 <code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 和 <code class="docutils literal notranslate"><span class="pre">serve-doc</span></code> 的目录必须加进
<code class="docutils literal notranslate"><span class="pre">PATH</span></code> 环境变量里，这些命令才能好好运行。</p>
</div>
<p>在 Debian/Ubuntu 、 Fedora 或 CentOS/RHEL 上执行此命令构建文档：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">admin/build-doc</span>
</pre></div></div><p>要扫描外部链接是否都可达，执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">admin/build-doc linkcheck</span>
</pre></div></div><p>执行 <code class="docutils literal notranslate"><span class="pre">admin/build-doc</span></code> 之后，它会在 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 下创建一个
<code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 目录。你也许还得在 <code class="docutils literal notranslate"><span class="pre">ceph/build-doc</span></code> 下创建个目录用于 Javadoc 的输出。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">mkdir -p output/html/api/libcephfs-java/javadoc</span>
</pre></div></div><p><code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 构建脚本可能会产生警告和报错，
有关语法的错误<strong>必须</strong>修复才能提交，
警告<strong>应该</strong>尽量消除。</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>你必须核实<strong>所有超链接</strong>，
损坏的超链接会中止构建过程。</p>
</div>
<p>文档构建完成后你就可以启动一个 HTTP 服务器、
通过 <code class="docutils literal notranslate"><span class="pre">http://localhost:8080/</span></code> 查看了：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">admin/serve-doc</span>
</pre></div></div><p>或者，你可以直接到 <code class="docutils literal notranslate"><span class="pre">build-doc/output</span></code> 下看看构建好的文档。那里应该有 <code class="docutils literal notranslate"><span class="pre">html</span></code> 目录和 <code class="docutils literal notranslate"><span class="pre">man</span></code> 目录分别存放着 HTML 和手册页格式的文档。</p>
<div class="section" id="id8">
<h4>构建源码（首次）<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h4>
<p>Ceph 用 Python Sphinx 构建文档，此软件一般都没安装。首次构建文档时，它会生成一个用于 doxygen 的 XML 树，这个过程比较耗时.</p>
<p>Python Sphinx 的依赖软件包根据发行版不同而有所区别。首次构建文档时，如果你没安装必要工具，构建脚本会提示你。要运行 Sphinx 并成功构建文档，至少要安装下面这些软件包：</p>
<style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style>
<table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3><ul class="simple">
<li><p>gcc</p></li>
<li><p>python3-dev</p></li>
<li><p>python3-pip</p></li>
<li><p>python3-sphinx</p></li>
<li><p>python3-venv</p></li>
<li><p>libxml2-dev</p></li>
<li><p>libxslt1-dev</p></li>
<li><p>doxygen</p></li>
<li><p>graphviz</p></li>
<li><p>ant</p></li>
<li><p>ditaa</p></li>
</ul>
</td><td><h3>Fedora</h3><ul class="simple">
<li><p>gcc</p></li>
<li><p>python-devel</p></li>
<li><p>python-pip</p></li>
<li><p>python-docutils</p></li>
<li><p>python-jinja2</p></li>
<li><p>python-pygments</p></li>
<li><p>python-sphinx</p></li>
<li><p>libxml2-devel</p></li>
<li><p>libxslt1-devel</p></li>
<li><p>doxygen</p></li>
<li><p>graphviz</p></li>
<li><p>ant</p></li>
<li><p>ditaa</p></li>
</ul>
</td><td><h3>CentOS/RHEL</h3><ul class="simple">
<li><p>gcc</p></li>
<li><p>python-devel</p></li>
<li><p>python-pip</p></li>
<li><p>python-docutils</p></li>
<li><p>python-jinja2</p></li>
<li><p>python-pygments</p></li>
<li><p>python-sphinx</p></li>
<li><p>libxml2-dev</p></li>
<li><p>libxslt1-dev</p></li>
<li><p>doxygen</p></li>
<li><p>graphviz</p></li>
<li><p>ant</p></li>
</ul>
</td></tr></tbody></table><p>缺少的依赖都要安装，基于 Debian/Ubuntu 发行版的系统可以用此命令安装：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo apt-get install gcc python-dev python-pip libxml2-dev libxslt-dev doxygen graphviz ant ditaa</span>
<span class="prompt1">sudo apt-get install python-sphinx</span>
</pre></div></div><p>在 Fedora 发行版上可以执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant</span>
<span class="prompt1">sudo pip install html2text</span>
<span class="prompt1">sudo yum install python-jinja2 python-pygments python-docutils python-sphinx</span>
<span class="prompt1">sudo yum install jericho-html ditaa</span>
</pre></div></div><p>在 CentOS/RHEL 发行版上，最好安装 <code class="docutils literal notranslate"><span class="pre">epel</span></code> (Extra Packages for
Enterprise Linux) 软件库，因为它提供了很多默认软件库所没有的软件包。可执行此命令安装 <code class="docutils literal notranslate"><span class="pre">epel</span></code> ：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm</span>
</pre></div></div><p>在 CentOS/RHEL 发行版上可以执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo yum install gcc python-devel python-pip libxml2-devel libxslt-devel doxygen graphviz ant</span>
<span class="prompt1">sudo pip install html2text</span>
</pre></div></div><p>对于 CentOS/RHEL 发行版，其余软件包不包含在默认及 <code class="docutils literal notranslate"><span class="pre">epel</span></code> 软件库内，所以得到 <a class="reference external" href="http://rpmfind.net/">http://rpmfind.net/</a> 找，然后到合适的镜像下载并安装它们，比如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm</span>
<span class="prompt1">sudo yum install python-jinja2-2.7.2-2.el7.noarch.rpm</span>
<span class="prompt1">wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm</span>
<span class="prompt1">sudo yum install python-pygments-1.4-9.el7.noarch.rpm</span>
<span class="prompt1">wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm</span>
<span class="prompt1">sudo yum install python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm</span>
<span class="prompt1">wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm</span>
<span class="prompt1">sudo yum install python-sphinx-1.1.3-11.el7.noarch.rpm</span>
</pre></div></div><p>Ceph 文档大量使用了 <a class="reference external" href="http://ditaa.sourceforge.net/">ditaa</a> ，
它没有对应的 CentOS/RHEL7 二进制包。
如果你要修改 <a class="reference external" href="http://ditaa.sourceforge.net/">ditaa</a> 图，
那你必须安装 <a class="reference external" href="http://ditaa.sourceforge.net/">ditaa</a> 才能确认你新增或修改的 <a class="reference external" href="http://ditaa.sourceforge.net/">ditaa</a> 图可以正确渲染。
你可以自己去找与 CentOS/RHEL7 发行版兼容的包，并手动安装。
在 CentOS/RHEL7 下 <a class="reference external" href="http://ditaa.sourceforge.net/">ditaa</a> 依赖下列软件包：</p>
<ul class="simple">
<li><p>jericho-html</p></li>
<li><p>jai-imageio-core</p></li>
<li><p>batik</p></li>
</ul>
<p>到 <a class="reference external" href="http://rpmfind.net/">http://rpmfind.net/</a> 找兼容的 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 及其依赖，
然后从某个镜像下载并安装它们。例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm</span>
<span class="prompt1">sudo yum install jericho-html-3.3-4.fc22.noarch.rpm</span>
<span class="prompt1">wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm</span>
<span class="prompt1">sudo yum install jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm</span>
<span class="prompt1">wget http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm</span>
<span class="prompt1">sudo yum install batik-1.8-0.12.svn1230816.el7.noarch.rpm</span>
<span class="prompt1">wget http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm</span>
<span class="prompt1">sudo yum install ditaa-0.9-13.r74.fc21.noarch.rpm</span>
</pre></div></div><p>安装好所有这些包之后，就可以按照<a class="reference internal" href="#id7">构建文档源码</a>里的步骤构建文档了。</p>
</div>
</div>
<div class="section" id="id9">
<h3>提交变更<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3>
<p>Ceph文档的提交虽然简单，却遵循着严格的惯例：</p>
<ul class="simple">
<li><p>一次提交<strong>应该</strong>只涉及一个文件（方便回退），
也<strong>可以</strong>一次提交有关联的多个文件。
不相干的变更<strong>不应该</strong>放到同一提交内；</p></li>
<li><p>每个提交都<strong>必须</strong>有注释；</p></li>
<li><p>提交的注释<strong>必须</strong>以 <code class="docutils literal notranslate"><span class="pre">doc:</span></code> 打头（应严格遵守）；</p></li>
<li><p>注释摘要<strong>必须</strong>只有一行（应严格遵守）；</p></li>
<li><p>额外的注释<strong>可以</strong>写到摘要下面空一行的地方，
但应该简单明了；</p></li>
<li><p>提交<strong>可以</strong>包含 <code class="docutils literal notranslate"><span class="pre">Fixes:</span> <span class="pre">https://tracker.ceph.com/issues/{bug</span> <span class="pre">number}</span></code> 字样；</p></li>
<li><p>提交<strong>必须</strong>包含 <code class="docutils literal notranslate"><span class="pre">Signed-off-by:</span> <span class="pre">Firstname</span> <span class="pre">Lasname</span> <span class="pre">&lt;email&gt;</span></code> （应严格遵守）。</p></li>
</ul>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>请遵守前述惯例，特别是标明了 <code class="docutils literal notranslate"><span class="pre">（应严格遵守）</span></code> 的那些，否则你的提交会被打回，
修正后才能重新提交。</p>
</div>
<p>下面是个通用提交的注释（首选）：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="p">:</span> <span class="n">Fixes</span> <span class="n">a</span> <span class="n">spelling</span> <span class="n">error</span> <span class="ow">and</span> <span class="n">a</span> <span class="n">broken</span> <span class="n">hyperlink</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">John</span> <span class="n">Doe</span> <span class="o">&lt;</span><span class="n">john</span><span class="o">.</span><span class="n">doe</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>下面的注释里有到 BUG 的引用。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="p">:</span> <span class="n">Fixes</span> <span class="n">a</span> <span class="n">spelling</span> <span class="n">error</span> <span class="ow">and</span> <span class="n">a</span> <span class="n">broken</span> <span class="n">hyperlink</span><span class="o">.</span>

<span class="n">Fixes</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">tracker</span><span class="o">.</span><span class="n">ceph</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">issues</span><span class="o">/</span><span class="mi">1234</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">John</span> <span class="n">Doe</span> <span class="o">&lt;</span><span class="n">john</span><span class="o">.</span><span class="n">doe</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>下面的注释包含一句概要和详述，
在摘要和详述之间用空行隔开了：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="p">:</span> <span class="n">Added</span> <span class="n">mon</span> <span class="n">setting</span> <span class="n">to</span> <span class="n">monitor</span> <span class="n">config</span> <span class="n">reference</span>

<span class="n">Describes</span> <span class="s1">&#39;mon setting&#39;</span><span class="p">,</span> <span class="n">which</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">new</span> <span class="n">setting</span> <span class="n">added</span>
<span class="n">to</span> <span class="n">config_opts</span><span class="o">.</span><span class="n">h</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">John</span> <span class="n">Doe</span> <span class="o">&lt;</span><span class="n">john</span><span class="o">.</span><span class="n">doe</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>执行下列命令提交变更：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git commit -a</span>
</pre></div></div><p>管理文档提交的一个比较简单的方法是用 <code class="docutils literal notranslate"><span class="pre">git</span></code> 的图形化前端，
如 <code class="docutils literal notranslate"><span class="pre">gitk</span></code> 提供了可查看仓库历史的图形界面；
<code class="docutils literal notranslate"><span class="pre">git-gui</span></code> 提供的图形界面可查看未提交的变更、
把未提交变更暂存起来、提交变更、
并推送到自己的 Ceph 分支仓库。</p>
<p>在 Debian/Ubuntu 上执行以下命令安装：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo apt-get install gitk git-gui</span>
</pre></div></div><p>在 Fedora/CentOS/RHEL 上执行以下命令安装：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo yum install gitk git-gui</span>
</pre></div></div><p>然后执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1"><span class="nb">cd</span> <span class="o">{</span>git-ceph-repo-path<span class="o">}</span></span>
<span class="prompt1">gitk</span>
</pre></div></div><p>最后，点击 <strong>File-&gt;Start git gui</strong> 打开图形界面。</p>
</div>
<div class="section" id="id10">
<h3>推送变更<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h3>
<p>你完成一或多个提交后，必须从本地推送到位于 <code class="docutils literal notranslate"><span class="pre">github</span></code> 的仓库。
某些图形化工具（如 <code class="docutils literal notranslate"><span class="pre">git-gui</span></code> ）有推送菜单。
如果你之前创建了分支：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git push origin wip-doc-<span class="o">{</span>your-branch-name<span class="o">}</span></span>
</pre></div></div><p>否则：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git push</span>
</pre></div></div></div>
<div class="section" id="id11">
<h3>发出接收请求<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h3>
<p>前面已经说过了，你可以依照<a class="reference external" href="https://help.github.com/articles/using-pull-requests">分支并拉取</a>方法共享文档。</p>
</div>
<div class="section" id="id12">
<h3>通知我们<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h3>
<p>如果发出的 PR 长时间没人审核，
请联系相应组件 <a class="reference internal" href="../../governance/#clt"><span class="std std-ref">Ceph 领导团队</span></a> 的负责人。</p>
</div>
</div>
<div class="section" id="id13">
<h2>文档风格指南<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h2>
<p>Ceph 文档项目的目标之一就是可读性，
包括 restructuredText 和渲染后的 HTML 页面的可读性。
进入 Ceph 源码库，随便找个文档查看其源码，
你会发现它们在终端下就像已经渲染过的 HTML 页面一样清晰明了。
另外，也许你还看到 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 格式的图表渲染的很漂亮。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">less doc/architecture.rst</span>
</pre></div></div><p>为了维持一致性，请遵守下面的风格手册。</p>
<div class="section" id="id14">
<h3>标题<a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li><p><strong>文档标题：</strong> 标题行的前、后各加一行 <code class="docutils literal notranslate"><span class="pre">=</span></code> ，
且标题行首、行尾各有一个空格，
详情见<a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle">文档标题</a>。</p></li>
<li><p><strong>段落标题：</strong> 段标题行下是一行 <code class="docutils literal notranslate"><span class="pre">=</span></code> ，且标题行首、
行尾都没有空格；段标题前应该有两个空行（除非前面是内嵌引用）。
详情见<a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections">小节</a>。</p></li>
<li><p><strong>小节标题：</strong> 小节标题行下是一行 <code class="docutils literal notranslate"><span class="pre">_</span></code> ，
且行首、行尾都没有空格；段标题前应该有两个空行
（除非前面是内嵌引用）。</p></li>
</ol>
</div>
<div class="section" id="id15">
<h3>正文<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h3>
<p>通常，我们把正文限制在 80 列之内，
这样它在任何标准终端内都可以正确显示，行首、行尾都不能有空格。
我们应该尽可能维持此惯例，包括文本、项目、文字文本
（允许例外）、表格、和 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 图形。</p>
<ol class="arabic">
<li><p><strong>段落：</strong> 段落前后各有一空行，
且宽度不超过 80 字符，
这样文档源码就可以在任何标准终端正确显示。</p></li>
<li><p><strong>引文文本：</strong> 要创建引文文本（如展示命令行用法），
前一段应以 <code class="docutils literal notranslate"><span class="pre">::</span></code> 结尾；
或者先加一个空行、然后在新行上输入 <code class="docutils literal notranslate"><span class="pre">::</span></code> 、
之后再加一个空行。
之后以 TAB （首选）或 3 个空格缩进，
开始输入引文了。</p></li>
<li><p><strong>缩进文本：</strong> 像要点这样的缩进文本（如： <code class="docutils literal notranslate"><span class="pre">-</span> <span class="pre">some</span> <span class="pre">text</span></code> ）
可能会延伸很多行，
后续行应该延续和首行缩进
（数字、圆点等）相同的起始列。</p>
<p>缩进文本也可以包含引文。这时，
缩进文本仍然用空格标记、引文仍用 TAB 标记。
按照这个惯例，你就可以额外增加缩进段落，
并在其中嵌入引文示例
（引文段前加空行，行前用空格缩进）。</p>
</li>
<li><p><strong>编号项目：</strong> 需编号的列表应该在行首用 <code class="docutils literal notranslate"><span class="pre">#</span></code> 标识以实现自动编号，
而不是手动标识，
这样在条目顺序变更时就不用重新编号了。</p></li>
<li><p><strong>代码示例：</strong> Ceph 文档中可以用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::&lt;language&gt;</span></code> 角色按语种对源码进行高亮显示，
对源代码应该这样标记。然而，
使用这个标签时将导致编号项目从 1 开始重新编号，
详情见<a class="reference external" href="http://sphinx-doc.org/markup/code.html">显示代码示例</a>。</p></li>
</ol>
</div>
<div class="section" id="id16">
<h3>段落分级标记<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h3>
<p>Ceph 文档项目用<a class="reference internal" href="#id16">段落分级标记</a>来高亮显示要点。</p>
<ol class="arabic simple">
<li><p><strong>Tip:</strong> 提示：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">tip::</span></code> 指令标识额外信息，
以助读者或操作员脱困。</p></li>
<li><p><strong>Note:</strong> 注：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">note::</span></code> 指令来高亮显示一个要点。</p></li>
<li><p><strong>Important:</strong> 重要：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">important::</span></code> 指令来高亮显示重要依赖或警告
（如可能导致数据丢失的事情）。
尽量少用，因为它会渲染成红色背景。</p></li>
<li><p><strong>Version Added:</strong> 版本新增：用 <code class="docutils literal notranslate"><span class="pre">..versionadded::</span></code> 指令来标识新增功能或配置选项，这样用户才能知道此选项适用的最低版本。</p></li>
<li><p><strong>Version Changed:</strong> 版本变更：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">versionchanged::</span></code> 指令标识用法或配置选项的变更。</p></li>
<li><p><strong>Deprecated:</strong> 已过时：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">deprecated::</span></code> 指令标识不再推荐或将被移除的 CLI 用法、功能、或配置选项。</p></li>
<li><p><strong>Topic:</strong> 论题：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">topic::</span></code> 指令来封装位于文档主体之外的文本。
详情见 <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic">topic 指令</a>。</p></li>
</ol>
</div>
<div class="section" id="toc">
<h3>TOC 和超链接<a class="headerlink" href="#toc" title="Permalink to this headline">¶</a></h3>
<p>所有文档都必须被链接到其他文档或列表内，
否则构建时会被警告。</p>
<p>Ceph 项目采用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">toctree::</span></code> 指令（详情见 <a class="reference external" href="http://sphinx-doc.org/markup/toctree.html">TOC 树</a>）。
渲染时，最好用 <code class="docutils literal notranslate"><span class="pre">:maxdepth:</span></code> 参数把 TOC 修饰得简洁些。</p>
<p>链接目标是个惟一标识符（如 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">_unique-target-id:</span></code> ）、
而且某一引用明确引用了它（如 <code class="docutils literal notranslate"><span class="pre">:ref:</span> <span class="pre">`uniq-target-id`</span></code> ），
这时应该优先用 <code class="docutils literal notranslate"><span class="pre">:ref:</span></code> 语法。这样，
如果源文件位置或文档结构变更之后链接仍然有效，
详情见<a class="reference external" href="http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref">交叉引用任意位置</a>。</p>
<p>Ceph 文档内的链接可以这样写：
反引号（重音符号）、之后跟着链接文本、另一个反引号、最后是下划线；
Sphinx 允许你内联链接目标。然而，我们喜欢这样用：
在文档底部加 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">_Link</span> <span class="pre">Text:</span> <span class="pre">../path</span></code> ，
因为这样的写法在命令行下可读性好。</p>
</div>
</div>
</div>



           </div>
           
          </div>
          <footer>
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
        <a href="../../install/" class="btn btn-neutral float-right" title="安装 Ceph" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
        <a href="../get-involved/" class="btn btn-neutral float-left" title="加入 Ceph 社区！" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>
        &#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).

    </p>
  </div> 

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>